home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / snippet.exe / C_PORT.TXT < prev    next >
Text File  |  1991-08-04  |  13KB  |  341 lines
  1.  
  2. =====[ Ed Hopper's BBS #1 ]=====[  8-04-91 ]=====[  9:55.22 ]=====
  3.  
  4.  
  5. Date: 08-02-91 (09:40)       C-Lang Number: 26406 (Echo)
  6.   To: ALL                      
  7. From: JOSEPH CARNAGE                  Read: 08-03-91 (10:56)
  8. City: DUNEDIN FL                   Last On: 02-28-91 (22:53)
  9. Subj: Portable, clean code #1  
  10.  
  11.                How to write portable clean source code
  12.                ---------------------------------------
  13.  
  14. A common concern with programmers new to Axiom is writing portable
  15. code.  There a number of tricks and guide lines which may help with
  16. this.  In no particular order:
  17.  
  18.   --  Use full ANSI prototypes with all arguments declared.  For
  19.       function pointers, declare their expected arguments.  For
  20.       prototypes for functions which accept function pointers, do not
  21.       declare the expected arguments for the function pointer
  22.       argument.
  23.  
  24.       It is good practice to put dummy variable names in prototypes as
  25.       this adds readability.
  26.  
  27.   --  Explicitly type all variables and functions.  Never rely on them
  28.       defaulting to int.
  29.  
  30.   --  Pay a little care to the ternary operator ? :, and parenthesize
  31.       heavily.  A very few compilers have problems with the default
  32.       order of evaluation for the ternary operator.
  33.  
  34.   --  Never ever name a variable identically to a function.  This is
  35.       most especially true of statics or globals.  This sort of error
  36.       can cause weird hidden linker problems which cause bizarre
  37.       results at runtime and are difficult to trace.
  38.  
  39.   --  Never ever name a screen, form, data field etc identically to a
  40.       variable or function as this can cause weird and non-reported
  41.       linker errors in the final executable which can be very
  42.       difficult to locate.
  43.  
  44.   --  Do not nest comments.  If you want to block off a section of
  45.       code temporarily, use #ifdef/#endif.  eg.
  46.  
  47.            ...code...
  48.          #ifdef JUNK /* Unwanted code */
  49.            ...more code...
  50.          #endif /* JUNK */
  51.            ...yet more code...
  52.  
  53.   --  Run PC-Lint on all code, and handle ALL errors and warnings.
  54.  
  55.   --  Read the "Frequently Asked Questions" document and understand
  56.       fully.
  57.  
  58.   --  Read K&R thoroughly and everywhere it mentions "implementation
  59.       dependant", or "new" features not "supported by all compilers",
  60.       avoid those areas.  Examples are bit fields, passing structures
  61.       to functions, returning structures from functions, and the
  62.       volatile type.  These are not supported by all compilers.
  63.  
  64.   --  In areas where the ANSI standard advances on the old K&R, but
  65.       still allows the K&R form, follow K&R.  An example is using
  66.       function pointers.  If you are unsure what areas this covers,
  67.       don't worry, just stick with K&R.  eg.
  68.  
  69.       Given:
  70.  
  71.         int (*prj_afunc) (); /* Pointer to function which returns int */
  72.  
  73.       ANSI allows the pointed to function be called as so:
  74.  
  75.         prj_afunc (xxx, yyy);
  76.  
  77.       K&R specifies that it should be called:
  78.  
  79.         *prj-afunc (xxx, yyy);
  80.  
  81.       Use the K&R form, which ANSI still allows, and all compilers
  82.       support.
  83.  
  84.   --  Do not use the new // comments.  Stay with the /* comment */
  85.       form.
  86.  
  87.   --  Do not indent #ifdefs, #defines, #pragmas, or other preprocessor
  88.       directives.  Some compilers allow code as such:
  89.  
  90.         #ifdef DEBUG
  91.           #define TEST 1
  92.         #endif
  93.  
  94.       or
  95.  
  96.         #ifdef FINAL
  97.         #  ifdef DEBUG
  98.         #    define TEST 1
  99.         #  endif
  100.         #endif
  101.  
  102.       But by no means all.  Use white space if needed to delineate
  103.       #ifdef/endif blocks and comment liberally:
  104.  
  105.         #ifdef FINAL
  106.  
  107.         #ifdef DEBUG
  108.         #define TEST 1
  109.         #endif /* DEBUG*/
  110.  
  111.         #endif /* FINAL */
  112.  
  113.   --  Do not use the ANSI string literal concatenation features.  eg.
  114.  
  115.         printf ("This is ANSI but"
  116.         "unportable code.\n");
  117.  
  118.       for long string literals.  Under ANSI the the compiler should
  119.       concatenate the two string literals into one, but not all ANSI
  120.       compilers support this feature yet.  If you need a very long
  121.       string literal use a form as so:
  122.  
  123.         printf ("%s%s",
  124.         "this is",
  125.         "portable code.\n");
  126.  
  127.       or just use a very long string literal.
  128.  
  129.   --  Stay away from ints except for trash and temp values.  Ints vary
  130.       in size depending upon the memory model under DOS, and legally
  131.       may be any size between shorts and longs inclusive.
  132.  
  133.       Try to use shorts or longs if possible, as these are of fairly
  134.       constant size on most platforms.  On most platforms, but by no
  135.       means all, shorts are usually words and longs word pairs.
  136.  
  137.   --  Beware of assigning a pointer of one type to a pointer of a
  138.       higher type.  Most platforms seem to insist that the addresses
  139.       stored in pointers are alligned per the pointer's base type.
  140.  
  141.       What this means is that the value stored in a pointer to a long,
  142.       in itself will be alligned as a long is.  If longs are alligned
  143.       on even word boundaries, then so will the value of long pointer.
  144.  
  145.       This can result in memory allignment errors which can be
  146.       extremely difficult to track down.  Casting will not help.
  147.  
  148.       DOS has few memory allignment requirements, but for Unix and VMS
  149.       you can expect types to be alligned to their sizes (see the
  150.       compiler manuals for specifics).  What this means to pointers is
  151.       that with code such as:
  152.  
  153.         short *pj2_value;  /* Assume that shorts are alligned to words */
  154.         long *pj4_number;  /* and longs to even word boundaries */
  155.  
  156.         pj4_number = pj2_value;
  157.  
  158.       that the value assigned to pj4_number may be as far as two bytes
  159.       different from that in pj2_value.  ie
  160.  
  161.         Let's say that the address stored is pj2_value is:
  162.  
  163.           *pj2_value == 0000:0006 /* Alligned to word */
  164.  
  165.         and you make the assignment:
  166.  
  167.           pj4_number = pj2_value;
  168.  
  169.        After this, the value of pj4_number will be either 0000:0004,
  170.        or 0000:0008 to shift it to even word allignment.  The
  171.        direction of the shift seems to be compiler/implementation
  172.        dependant.
  173.  
  174.        This bug is often erratic at runtime depending upon the
  175.        allignment of automatics.  This sort of bug is especically
  176.        difficult to track when coming up from a void pointer.
  177.  
  178.   --  Be wary of relying on memory allignment in structures and
  179.       unions.  Different compiler implmentations allign differently,
  180.       and #pragmas or command line arguments to the compiler can
  181.       change allignment at compile time.  See the compiler manuals for
  182.       specific details.
  183.  
  184.       This will usually require you to either read in each member
  185.       individually, or to perform explicit padding when reading
  186.       structure data from disk.  eg. lic1.c & v_lic_pad() in the Axiom
  187.       library.
  188.  
  189.   --  Where possible use sizeof(identifier) rather than sizeof(type)
  190.       or a #defined constant. This can help in tracing down bugs and
  191.       makes for greater readability.  eg.
  192.  
  193.           #define M_DATA 100
  194.           short aj2_numbers[M_DATA];
  195.  
  196.         /* This example requires the reader to remember that
  197.         aj2_numbers has M_DATA elements, is overly complex, and
  198.         presumes that aj2_numbers will always be shorts.  This code
  199.         will likely break if anything is later changed. */
  200.  
  201.           memcpy (aj2_numbers, pj2_input, M_DATA * sizeof (short));
  202.  
  203.         /* This is ideal -- sizeof(aj2_numbers) will return the total
  204.         space allocated to the array, no matter what the type may be,
  205.         or what is changed later.  It makes no assumptions of the
  206.         reader. */
  207.  
  208.           memcpy (aj2_numbers, pj2_input, sizeof (aj2_numbers));
  209.  
  210.   --  Beware of comparing structures or unions with functions such as
  211.       memcmp() as the padding/allignment spaces will have random and
  212.       likely different values.  If you need to compare structures
  213.       you'll have to do it member by member.
  214.  
  215.   --  Never assign structures to each other directly.  Some compiler